<!-- HTML header for doxygen 1.8.13-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>MTB CAT1 Peripheral driver library: FreeRTOS Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen_style.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><a href="http://www.cypress.com/"><img alt="Logo" src="IFXCYP_one-line.png"/></a></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">MTB CAT1 Peripheral driver library</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('page_freertos_overview.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">FreeRTOS Overview </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1>What is FreeRTOS</h1>
<p>FreeRTOS is a small operating system intended for use on microcontrollers. It implements a system of threads and semaphores that enable the developer to write an application that works as a set of independent threads that communicate using message queues. The FreeRTOS API Documentation is <a href="http://www.freertos.org/a00106.html" target="_blank">here</a>. A good place to start understanding the design is at the <a href="http://www.freertos.org/Creating-a-new-FreeRTOS-project.html">Creating a New FreeRTOS Project</a> topic in the FreeRTOS documentation.</p>
<h1>How to Configure</h1>
<p>FreeRTOS is supplied as standard C source files that are be built along with the other C files in your project.</p>
<p>Every project also requires a file named FreeRTOSConfig.h. The <a href="http://www.freertos.org/a00110.html" target="_blank">Customization</a> documentation tells you that “FreeRTOSConfig.h tailors the RTOS kernel to the application being built. It is therefore specific to the application, not the RTOS”.</p>
<p>A developer modifies the macros in this file to customize the RTOS behavior to fit the application requirements. Consult the FreeRTOS documentation for details. These items are discussed here:</p>
<p>configCPU_CLOCK_HZ</p>
<p>configTOTAL_HEAP_SIZE</p>
<p>configHEAP_ALLOCATION_SCHEME</p>
<p>configMINIMAL_STACK_SIZE</p>
<p>configMAX_SYSCALL_INTERRUPT_PRIORITY</p>
<dl class="section note"><dt>Note</dt><dd>If you call a FreeRTOS API function from an interrupt with priority higher than MAX_API_CALL_INTERRUPT_PRIORITY FreeRTOS will generate an exception. Possible solutions are:<ol type="1">
<li>Reduce all interrupt priorities to MAX_API_CALL_INTERRUPT_PRIORITY or lower</li>
<li>Trig interrupt with priority less or equal MAX_API_CALL_INTERRUPT_PRIORITY and call FreeRTOS API from this interrupt handler</li>
<li>Call FreeRTOS API from traceTASKSWITCHEDOUT() macro. <a href="https://www.freertos.org/FreeRTOS_Support_Forum_Archive/October_2014/freertos_How_to_wake_up_a_FreeRtos_task_from_a_high_priority_ISR_140cde98j.html">see FreeRTOS support</a></li>
</ol>
</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>If your system pipe (IPC) interrupt priority is less than or equal to MAX_API_CALL_INTERRUPT_PRIORITY then care must be taken with code that writes to flash (including the Flash/Bluetooth<sup>&reg;</sup> LE/Emulated EEPROM/Bootloader SDK). The duration of critical sections must be kept short - see the <a class="el" href="group__group__flash.html#group_flash_configuration">Configuration Considerations</a> section of the flash driver.</dd></dl>
<h1>Clock Frequency</h1>
<p>FreeRTOS task scheduling and blocking is based on a tick count, which in turn is based on the clock frequency. The configCPU_CLOCK_HZ specifies the frequency. The FreeRTOSConfig.h file provided with the PDL sets this value for you as cy_delayFreqHz. This value is calculated by the system startup code.</p>
<h1>FreeRTOS Memory Management</h1>
<p>FreeRTOS requires memory. The amount of memory required and how to manage that memory varies per application. To allow for this variation, FreeRTOS implements several different memory management schemes. These are implemented in source files named heap_1.c, heap_2.c, up through heap_5.c. Each scheme is documented in the FreeRTOS <a href="http://www.freertos.org/a00111.html">Memory Management</a> topic. These files are in the <em>&lt;PDL directory&gt;/rtos/FreeRTOS/&lt;FreeRTOS version&gt;/Source/portable/MemMang</em> directory.</p>
<p>The memory management schemes included in FreeRTOS:</p>
<ul>
<li><a href="http://www.freertos.org/a00111.html#heap_1">heap_1</a> - the very simplest, does not permit memory to be freed</li>
<li><a href="http://www.freertos.org/a00111.html#heap_2">heap_2</a> - permits memory to be freed, but not does coalesce adjacent free blocks.</li>
<li><a href="http://www.freertos.org/a00111.html#heap_3">heap_3</a> - simply wraps the standard malloc() and free() for thread safety</li>
<li><a href="http://www.freertos.org/a00111.html#heap_4">heap_4</a> - coalesces adjacent free blocks to avoid fragmentation. Includes absolute address placement option.</li>
<li><a href="http://www.freertos.org/a00111.html#heap_5">heap_5</a> - as per heap_4, with the ability to span the heap across multiple non-adjacent memory areas</li>
</ul>
<p>In the heap_3 memory scheme, your linker file specifies a heap and stack of sufficient size, and your firmware must implement and use malloc() and free() to allocate and release memory.</p>
<p>In the other memory schemes, the RTOS allocates a stack and heap.</p>
<p>For these schemes, the stack defined in the PDL linker file is used only by main() and the functions it calls. The stack can be reduced to the value needed by these functions. The FreeRTOSConfig.h definition configMINIMAL_STACK_SIZE sets the size of the stack used by the idle task. If configMINIMAL_STACK_SIZE is set too low, then the idle task will generate stack overflows.</p>
<p>For memory schemes other than heap_3, the project uses the configTOTAL_HEAP_SIZE definition in FreeRTOSConfig.h. In this case the heap defined in the PDL linker file can be reduced to 0, if you are not using functions like printf(). Set configTOTAL_HEAP_SIZE to the size required for the application. Your application will not link if configTOTAL_HEAP_SIZE is set too high.</p>
<p>For more details on Memory Management schemes see the <a href="http://www.freertos.org/a00111.html">FreeRTOS Documentation</a> page.</p>
<p>The parameter configHEAP_ALLOCATION_SCHEME defines memory management scheme used in the project.</p>
<h1>Using FreeRTOS in a PSoC&trade; Creator project</h1>
<p>The FreeRTOS code example has projects for third-party IDEs. To use FreeRTOS with PSoC&trade; Creator, create a PSoC&trade; Creator project. Then click Project &gt; Build Setting &gt; Peripheral Driver Library, here you may choose the PDL software packages. To add FreeRTOS source files to your project, enable it as it is shown in the screenshot below: </p><div class="image">
<img src="FreeRTOS_build_settings.png" alt="FreeRTOS_build_settings.png"/>
<div class="caption">
Figure 1. Build Settings dialog in PSoC&trade; Creator</div></div>
<p> After selecting FreeRTOS in the PDL software package list, click OK. PSoC&trade; Creator adds the FreeRTOS source files to the project the next time you generate the application. Use "#include" statements in your code to include FreeRTOS header files. PSoC&trade; Creator does not include them automatically, because there could be order dependencies in your project.</p>
<p>When you build your code with FreeRTOS files for the first time, the compiler will issue a build warning to remind you to enter proper configuration in the FreeRTOSConfig.h file. When you have done so, remove that warning message from the FreeRTOSConfig.h file.</p>
<div class="image">
<img src="FreeRTOS_warning.png" alt="FreeRTOS_warning.png"/>
<div class="caption">
Figure 2. Build warning after first build of the project with included FreeRTOS sources</div></div>
 <h1>Using FreeRTOS in a ModusToolbox&trade; project</h1>
<p>Use Middleware Selector with mainapp project to add FreeRTOS to existing ModusToolbox&trade; project. Open Middleware Selector and select FreeRTOS item. After selecting FreeRTOS in the Middleware list, click OK. Middleware Selector adds the FreeRTOS source files to the project. Use "#include" statements in your code to include FreeRTOS header files.</p>
<p>When you build your code with FreeRTOS files for the first time, the compiler will issue a build warning to remind you to enter proper configuration in the FreeRTOSConfig.h file. When you have done so, remove that warning message from the FreeRTOSConfig.h file. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part
<div id="nav-path" class="navpath">
    <ul>
        <li class="footer">
            Generated for <b>MTB CAT1 Peripheral driver library</b> by <b>Cypress Semiconductor Corporation</b>.
            All rights reserved.
        </li>
    </ul>
</div>
-->
</body>
</html>
